Skip to main content

Aspect Template Families

The Forge CLI ships a curated catalog of Aspect templates derived from real production patterns that we see across FIs. Each template is paired with one or more presets that fill in mock vendor URLs enabling you to preview, edit, and validate the end-to-end integration without leaving your laptop.

This page is a quick map of those families. Use it to find the closest starting point for an integration, then run forge aspect templates <id> for the full prompt list and forge aspect preview --template <id> --preset <id> to see it in action.

How Templates Are Organized​

AxisValuesWhat it controls
platformweb, mobile, bothWhich surfaces the template can target. Mobile-only families emit full WebView HTML.
categorycontext-less, context-awareWhether the snippet reads dbk.sessionInfo() / OIDC / a JSBridge token.
contextMethodglobal-variable, oidc, jsbridge-token (context-aware only)The session-bridging boilerplate the template emits.

You can filter the catalog interactively:

Bash
forge aspect templates --platform web --context-aware
forge aspect templates --platform mobile
forge aspect templates --preset glia

Family Catalog​

Vendor Script Loader​

  • Template id: vendor-script-loader
  • Platform: both  ·  Category: context-less
  • Pattern: A single dbk.loadScript(url) call that points at a vendor SDK which self-mounts (chat bubble, engagement banner, etc.). No personalization needed.
  • What the user sees / CTA: Whatever the vendor SDK draws — typically a floating chat or engagement bubble.
  • Action behavior: All interaction is owned by the vendor SDK after load.
  • Presets:
    • glia — Mock Glia chat bubble served from the local vendor server.
  • Production examples it replaces: The "drop-in chat / engagement loader" Aspects deployed for ~25% of FIs.

Vendor Script with Config​

  • Template id: vendor-script-with-config
  • Platform: both  ·  Category: context-less
  • Pattern: Loads a vendor JS + CSS pair, but first writes tenant-flavored configuration onto window.* so the SDK can pick it up on init.
  • What the user sees / CTA: A vendor widget themed to the FI (retail vs business flavors are common).
  • Action behavior: The vendor SDK reads window.AspectConfigContent (or similar) and customizes itself before mounting.
  • Presets:
    • link-live-retail — Link Live retail config, served from /link-live/handoff/retail.
    • link-live-business — Link Live business config, served from /link-live/handoff/business.

Tag Manager​

  • Template id: tag-manager
  • Platform: web  ·  Category: context-less
  • Pattern: Standard Google Tag Manager bootstrap (dataLayer + script injection) for a single container id. Web-only — mobile native analytics use platform SDKs, not GTM.
  • What the user sees / CTA: Nothing visible. Analytics events are captured server-side.
  • Action behavior: Pageviews and configured custom events flow into GTM → downstream analytics.
  • Presets:
    • gtm — Mock GTM container GTM-MOCK000 so the snippet works against the local vendor server.

Hidden Iframe SSO Handoff​

  • Template id: hidden-iframe-sso
  • Platform: both  ·  Category: context-aware  ·  Method: oidc
  • Pattern: Mounts a hidden iframe pointed at a vendor handoff endpoint, which postMessages back an SSO token. The Aspect listens, validates the origin, and forwards the token to whatever vendor surface needs it.
  • What the user sees / CTA: Nothing — the iframe is display:none. The visible UI is whatever the vendor surface renders after the token lands (for example, chat, secure messaging, etc.).
  • Action behavior: On message the Aspect either dispatchEvents a custom ready event or hands the token to a follow-up SDK init.
  • Presets:
    • iframe-sso — Local /sso/handoff mock that posts back a synthetic access_token.
  • Optional flag: webviewGate: true skips mount when dbk.isWebview() is true.

Vendor SDK with Personalization​

  • Template id: vendor-sdk-personalized
  • Platform: both  ·  Category: context-aware  ·  Method: global-variable
  • Pattern: Loads a vendor SDK and pre-seeds it with dbk.sessionInfo() before the SDK boots — so chat starts already knowing the user's name and id.
  • What the user sees / CTA: A vendor chat / co-browse / engagement widget where the user is already identified.
  • Action behavior: Click → vendor SDK opens with PreChatFields (or equivalent) prepopulated.
  • Presets:
    • salesforce-chat — Mock Salesforce Embedded Service chat.
    • five9-chat — Mock Five9 chat plugin.
    • acquire-cobrowse — Mock Acquire co-browse / chat widget.

Floating Action Button​

  • Template id: floating-action-button
  • Platform: both  ·  Category: context-less
  • Pattern: A fixed-position button (icon is optional) that opens a URL in a new tab. Captures the "help / FAQ deep link" pattern that several FIs roll on their own.
  • What the user sees / CTA: A circular button anchored to the bottom-right with the configured label / icon.
  • Action behavior: Click → window.open(url, '_blank', 'noopener,noreferrer').
  • Presets:
    • fab-help — Help icon FAB pointed at the local /help mock route.

Mobile Vendor Chat (JSBridge)​

  • Template id: mobile-vendor-chat-jsbridge
  • Platform: mobile  ·  Category: context-aware  ·  Method: jsbridge-token
  • Pattern: Mobile-only WebView template. Requests a session token via the native JSBridge (iOS webkit.messageHandlers.tokenApiDetails, Android JSBridge.tokenApiDetails) and uses it to init a vendor chat SDK. Falls back to a POST /token endpoint when no JSBridge is present so the template is also previewable in dev.
  • What the user sees / CTA: A vendor mobile chat experience already authenticated as the user.
  • Action behavior: The Aspect dispatches cdx-mobile-vendor-ready once the token + SDK are loaded; the vendor SDK listens and bootstraps itself.
  • Presets:
    • mobile-ujet — Mock UJET mobile SDK.
    • mobile-salesforce — Mock Salesforce mobile chat SDK.

Previewing Against the Mock Partner Server​

All presets default to http://localhost:4011, which is served by the public cdx-mock-partners repository. It serves:

  • GET /vendors/<vendor>/<file> — mock vendor SDK assets (JS/CSS).
  • GET /sso/handoff — fake SSO landing page used by hidden-iframe-sso.
  • POST /token — fake JSBridge token endpoint used by mobile-vendor-chat-jsbridge.
  • GET /link-live/handoff/:variant — JSON config for vendor-script-with-config.
  • GET /help — destination for the floating-action-button preset.

forge aspect preview automatically detects whether the mock partner server is up and uses it when present, so the typical workflow is:

Bash
# In one terminal — start cdx-mock-partners
cd cdx-mock-partners && pnpm install && pnpm start

# In another — preview a template
forge aspect preview --template vendor-sdk-personalized --preset salesforce-chat

Each mock SDK draws a MOCK · pill with the partner name (usually bottom-right). Click the pill (or press Enter while it is focused) to open a panel that summarizes what the real integration does, offers one-click simulated partner actions (appended to window.__mockPartnerCalls), and shows the rolling call log. The hidden-iframe-sso template adds a separate MOCK · SSO pill (bottom-left) after the token arrives; click it to inspect the mock payload. The floating-action-button preset shows a brief Opening help… status chip before the new tab, and the /help mock page includes a Reveal typical post-navigation content control so you can see a second-step interaction without a real CMS.

One-page gallery​

Once cdx-mock-partners is up and cdx-forge-cli has been built (sibling checkout; see that repo’s README for FORGE_CLI_DIST), visit http://localhost:4011/gallery. The gallery lists every (template, preset) combo we ship and runs the real generated code in a sandboxed iframe on the right. It's the fastest way to eyeball every family without spinning up the OLB Docker playground.

Authoring Your Own​

When you want a behavior that isn't covered by an existing family:

  1. Start from the closest preset — forge aspect preview --template <id> --preset <id> and edit the prompts/options.
  2. Generate a file you can edit: forge aspect preview --template <id> --preset <id> --preview-code > my-aspect.js.
  3. If the pattern recurs across FIs, propose a new template upstream. The CLI's README.md has the contributor checklist (mock SDK + e2e test + PII scan).

For additional details on how Aspects execute, see the Web Technical Reference and Mobile Technical Reference sections.

Built-in Security Controls​

The CLI applies the following hardening to emitted snippets so authors and FI security reviewers get a safe baseline by default. Templates marked (personalized) read dbk.sessionInfo() and therefore inline session validation.

TemplateXSS validationURL / origin filterCSP-friendly handlersCSP nonce on <style>SRI supportSandbox / msg validationFetch timeout + retryCorrelation id
welcome-banner (personalized)✓—✓✓n/an/an/a—
personalized-toast (personalized)✓—✓✓n/an/an/a—
banner, toast, countdownescaped message—✓✓n/an/an/a—
cardescaped message + CTA label✓ (ctaUrl)✓✓n/an/an/a—
modalescaped message + CTA label✓ (ctaUrl)✓✓n/an/an/a—
vendor-script-loadern/a—inline events from vendor SDKn/a✓ JSn/an/a—
vendor-script-with-confign/a—inline events from vendor SDKn/a✓ JS + CSSn/an/a—
tag-managern/a—inline events from GTMn/a✓ JSn/an/a—
vendor-sdk-personalizedn/a—inline events from vendor SDKn/a✓ JSn/an/a—
mobile-vendor-chat-jsbridgen/a—inline events from vendor SDKn/a✓ JSn/a✓ fallback fetch✓
hidden-iframe-sson/a✓ origin allowlist✓n/an/a✓ iframe sandbox + token scheman/a✓
oidc-snippetn/an/a✓✓n/an/a✓ toolkit + production✓

Validators inlined into the snippet (no runtime imports, no dbk.* dependency):

  • __cdxValidateSession(session) — Q14: type/length/character/expiry checks on dbk.sessionInfo().
  • __cdxEsc(str) — Q23: HTML entity encoding for &<>"'/.
  • __cdxValidateHttpUrl(url) — Q24: rejects anything other than http: / https:.

SRI for vendor scripts (Q11): pass --integrity 'sha{256,384,512}-<base64>' (and optionally --crossorigin) to forge aspect preview or forge aspect submit. The CLI validates the hash format at generation time, applies script.integrity + script.crossOrigin attributes at runtime, and bypasses dbk.loadScript (which can't apply SRI) with a console warning. vendor-script-with-config additionally accepts --css-integrity / --css-crossorigin for the CSS <link> tag. A malformed hash is rejected at generation time and the template falls back to loading without SRI plus a console.error. See the Web security model for the full rationale and openssl recipe.

SSO iframe hardening for hidden-iframe-sso (Q8 / Q18 / Q19 / Q20): the iframe is sandboxed (allow-same-origin allow-scripts by default, override with --iframe-sandbox), postMessage origins are matched against an allowlist (the iframe's own origin is always trusted; extend via --allowed-origins 'https://idp.example.com,*.federation.example.com'), the token payload is strictly validated (type==='sso-token', non-empty token ≤ 4096 chars, future expiry, optional ≤ 1024-char signature), and unknown fields are stripped before dispatch. The custom event uses bubbles:false / composed:false. See the SSO iframe hardening section.

Fetch resiliency for oidc-snippet and mobile-vendor-chat-jsbridge (Q30 / Q31 / Q33): all fetch calls go through an inlined __cdxFetch helper with AbortController-based timeout (default 10 s), exponential-backoff retries on 5xx (default 3, capped at 8 s of backoff), no retry on 4xx, and a timeout-specific error path. Tune via --timeout-ms <1000-60000>, --max-retries <0-5>, and --retry-delay-ms <100-10000>. Out-of-range values fall back to runtime defaults silently. See the Fetch resiliency section.

Strict-CSP support (Q24): every emitted snippet is now free of inline onclick= / onerror= / onload= handlers — close and dismiss buttons use data-cdx-action attributes plus addEventListener. Inline <style> blocks for the keyframe animations accept an optional --csp-nonce <value> flag that stamps the FI's per-request nonce on every emitted <style> element so the snippet runs under style-src 'nonce-<value>'. Phase 6 also back-ported the __cdxValidateHttpUrl protocol filter to the card template's ctaUrl (was previously inlined as <a href="${ctaUrl}">). See the CSP nonce section.

Correlation IDs for incident response (Q35): the three templates that cross trust boundaries — oidc-snippet, mobile-vendor-chat-jsbridge, hidden-iframe-sso — auto-generate a per-snippet correlation id (format: aspect_<base36-ts>_<base64url-rand>) and prefix every console.* line with [cdx-aspect:<id>]. Override via --correlation-id <value> to chain logs from your CI / release pipeline. Other templates keep the legacy [cdx-aspect] prefix without a per-instance id (no telemetry consumer). See the Correlation IDs section.

Coverage gaps: Shadow DOM CSS isolation, HMAC verification on the SSO signature field (currently type-checked only), and a centralized telemetry pipeline (correlation IDs land in console.*). Hand-written Aspects must implement equivalents — see the Web security model.

For FI / AppSec reviewers: the Security Questionnaire (Vendor Response) reproduces all 60 questions verbatim, ships a coverage matrix per template, and pre-fills completed responses for oidc-snippet, hidden-iframe-sso, and mobile-vendor-chat-jsbridge. The Security Architecture page covers the trust-zone diagram and party responsibilities. The Deployment Security Checklist is the pre-deployment review worksheet with concrete grep commands and sign-off lines.